SapphireIMS API Documentation · ITSM, CMDB & Platform

Authentication & Common Headers

The following headers are required on most endpoints. Endpoints that require API key and token are marked individually.

Header	Type	Required	Description
`int-log-id`	String	REQUIRED	Integration log identifier for request tracing and audit
`X-API-KEY`	String	REQUIRED*	API key credential — required on GET and Search endpoints
`TOKEN`	String	REQUIRED*	Authentication token — required on GET and Search endpoints
`Content-Type`	String	REQUIRED	`application/json` for JSON endpoints, `multipart/form-data` for file uploads, `application/octet-stream` for stream upload

💡 Recommended Postman practice: store {{baseUrl}}, {{apiKey}}, and {{token}} as Collection Variables and use them across all requests.

Ticket Lifecycle

POST /ticket/create Creates a new service desk ticket ▼

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES

💡 Each reference object carries both the base id/name fields and the type-specific aliases (e.g. serviceId/serviceName) together in the same object. See Common Schemas for the full field mapping per type.

Request Body

JSON

{
  "requestType": "CREATE_TICKET",
  "requestTime": "2024-01-15T10:30:00.000Z",
  "integrationLogId": "LOG-001",
  "iteration": 0,
  "ticket": {
    "templateId": 1,

    "project": {
      "id": 1, "name": "IT Support",
      "projectId": 1, "projectName": "IT Support"
    },

    "service": {
      "id": 10, "name": "Email Services",
      "serviceId": 10, "serviceName": "Email Services"
    },

    "title": "Email not working",
    "probDescription": "Unable to send or receive emails since this morning.",

    "submittedBy":     { "userId": 101 },
    "owner":           { "userId": 202 },
    "approvalManager": { "userId": 303 },

    "currentState": {
      "id": 1, "name": "Open",
      "stateId": 1, "stateName": "Open"
    },

    "category": {
      "id": 5, "name": "Hardware",
      "categoryId": 5, "categoryName": "Hardware"
    },

    "subCategory": {
      "id": 12, "name": "Laptop",
      "subcategoryId": 12, "subcategoryName": "Laptop"
    },

    "location": { "id": 3, "name": "Chennai HQ" },

    "department": { "id": 7, "name": "Finance" },

    "priority": { "id": 2, "name": "High" },

    "urgency":  { "id": 1, "name": "Critical" },

    "impact":   { "id": 1, "name": "High" },

    "derivedField1": {
      "id": 8, "name": "Region",
      "derivedFieldId": 8, "derivedFieldName": "Region"
    },
    "derivedField2": { "id": 0 },
    "derivedField3": { "id": 0 },

    "workGroup": { "id": 4, "name": "L1 Support" },

    "source": { "id": 1, "name": "Portal" },

    "ccMailId":          "cc@example.com",
    "alternativeEmail":  "alt@example.com",
    "contactNumber":     "9876543210",
    "resolutionComment": "",
    "resolutionCauseId": 0,
    "resolutionDays":    "0",
    "resolutionHours":   "0",
    "resolutionMinutes": "0",
    "expectedClosureTime": "",
    "requestType":  1,
    "incidentType": 0,
    "latitude":     "12.9716",
    "longitude":    "77.5946",

    "additionalParams": {
      "attribute1": { "fieldid": 101, "data": "Free text value" },
      "attribute2": { "fieldid": 102, "data": "2024-01-15" },
      "attribute3": { "fieldid": 103, "data": "2024-01-15 14:30" },
      "attribute4": { "fieldid": 104, "data": "Option1,Option2" },
      "attribute5": { "fieldid": 105, "data": "SelectedOption" },
      "attribute6": {
        "fieldid": 106,
        "grid": {
          "noOfRow": 2,
          "rows": [
            {
              "attribute1": { "fieldid": 201, "data": "row1-col1-value" },
              "attribute2": { "fieldid": 202, "data": "row1-col2-value" }
            },
            {
              "attribute1": { "fieldid": 201, "data": "row2-col1-value" },
              "attribute2": { "fieldid": 202, "data": "row2-col2-value" }
            }
          ]
        }
      }
    }
  }
}

Key Fields — ticket object

Field	Type	Required	Description
`project.id`	Integer	YES	Project ID. Alternatively use `project.name`.
`service.id`	Integer	YES	Service catalogue item ID. Alternatively use `service.name`.
`title`	String	optional	Ticket title / subject. Set only if provided — no server-side mandatory check.
`probDescription`	String	optional*	Detailed description. Mandatory only if the project's fixed-field configuration marks it required.
`submittedBy.userId`	Integer	optional	User ID of the requester. Alternatively use `submittedBy.userName`. Defaults to system user (ID 4) if omitted.
`currentState.id`	Integer	N/A	Ignored on create — server always sets the project's configured start state automatically.
`category.id`	Integer	optional	Category ID
`subCategory.id`	Integer	optional	Sub-category ID
`priority.id`	Integer	optional	Priority ID
`urgency.id`	Integer	optional	Urgency ID
`impact.id`	Integer	optional	Impact ID
`owner.userId`	Integer	optional	Assigned technician user ID
`workGroup.id`	Integer	optional	Work group / team ID
`templateId`	Integer	optional	Quick-call / ticket template ID
`ccMailId`	String	optional	CC email addresses (comma-separated)
`contactNumber`	String	optional	Requester contact number
`latitude` / `longitude`	String	optional	Geo-coordinates of the issue location
`additionalParams`	Object	optional	Custom additional fields — see field-type reference below

additionalParams — Field Type Reference

Each entry in additionalParams maps a slot (attribute1 … attribute50+) to an Attribute object with fieldid (the project-configured field ID) and either a data string or a grid object, depending on the field type. Obtain the correct fieldid and field type from the project's additional-field configuration.

Field Type	Type ID	`data` Format	Example
Text Box	1	Any plain string. Must match configured regex pattern/mask if set.	`"data": "John Doe"`
Select Box (Dropdown)	2	Exact option value string from the configured dropdown list.	`"data": "Hardware"`
Date And Time Field	3	`yyyy-MM-dd HH:mm` (24-hour)	`"data": "2024-01-15 14:30"`
Text Area	4	Multi-line plain text string.	`"data": "Detailed notes here"`
Radio Button	5	Exact option value string from the configured radio options.	`"data": "Yes"`
Multi Select Box	6	Comma-separated option values. Each value is stored as a separate record. No spaces around the comma.	`"data": "Option1,Option2,Option3"`
Check Box (YES/NO)	7	`"true"` or `"false"` as a string.	`"data": "true"`
Title / Sub-Title / Label / HTML Content	8, 9, 10, 17	Display-only fields. No `data` needed — omit the attribute entirely.	—
Inventory Field	11	Plain string value.	`"data": "INV-00123"`
Searchable Multi Select Box	12	Comma-separated option values (same format as Multi Select Box).	`"data": "Tag1,Tag2"`
Grid Control	13	No `data` field. Use the `grid` object with `noOfRow` and a `rows` array. Each row is an object of `attribute1`…`attributeN` entries keyed by the grid column's `fieldid`.	See grid example below
File Upload	14	Cannot be submitted inline in the ticket JSON body. Files must be uploaded via the attachment upload endpoint separately and linked by ticket ID after creation.	—
Date Field	15	`yyyy-MM-dd`	`"data": "2024-01-15"`
Static Grid	16	Display-only. No data required.	—
Calendar Event	18	Uses the `grid` object (same structure as Grid Control).	See grid example below
Hyperlink	20	A valid URL string.	`"data": "https://example.com"`
Time Field	21	`HH:mm` (24-hour)	`"data": "09:30"`
Editable Select Box	22	Existing option value or free-text string.	`"data": "Custom Value"`
Editable Multi Select Box	23	Comma-separated values (existing options or free-text).	`"data": "Value1,Value2"`

Grid Control — Attribute Structure

JSON

"additionalParams": {
  "attribute6": {
    "fieldid": 106,
    "grid": {
      "noOfRow": 2,
      "rows": [
        {
          "attribute1": { "fieldid": 201, "data": "Row 1 — Column A value" },
          "attribute2": { "fieldid": 202, "data": "Row 1 — Column B value" },
          "attribute3": { "fieldid": 203, "data": "2024-01-15" }
        },
        {
          "attribute1": { "fieldid": 201, "data": "Row 2 — Column A value" },
          "attribute2": { "fieldid": 202, "data": "Row 2 — Column B value" },
          "attribute3": { "fieldid": 203, "data": "2024-01-20" }
        }
      ]
    }
  }
}

Grid notes: noOfRow must equal the number of entries in the rows array. The fieldid values for the column attributes (attribute1, attribute2, …) are the child column field IDs, not the parent grid field ID. Column attribute data formats follow the same field-type rules in the table above. Grid columns can support Text Box, Date Field, Select Box, and other simple types.

Response

● 200 OK

JSON

{
  "requestType":      "CREATE_TICKET",
  "requestTime":      "2024-01-15T10:30:00.000Z",
  "responceTime":     "2024-01-15T10:30:01.500Z",
  "integrationLogId": "LOG-001",
  "iteration":        0,
  "problemId":        4521,
  "requestNumber":    "INC-2024-00123"
}

POST /ticket/update Updates fields on an existing ticket ▼

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES

Important — updated: true is required to save changes. For every field object (fixed fields and additional params) you want the server to write, you must include "updated": true inside that field's object. If updated is absent or false, the field is validated but the update is silently skipped — the existing value is kept. ticket.problemId must identify the existing ticket.

Request Body

JSON

{
  "requestType": "UPDATE_TICKET",
  "requestTime": "2024-01-15T11:00:00.000Z",
  "integrationLogId": "LOG-002",
  "iteration": 1,
  "ticket": {
    "problemId":       4521,
    "title":           "Email not working — updated",
    "probDescription": "Updated description after initial investigation.",

    "owner":    { "userId": 205, "updated": true },

    "priority": { "id": 2, "name": "High", "updated": true },

    "category": {
      "id": 5, "name": "Hardware",
      "categoryId": 5, "categoryName": "Hardware",
      "updated": true
    },

    "subCategory": {
      "id": 12, "name": "Laptop",
      "subcategoryId": 12, "subcategoryName": "Laptop",
      "updated": true
    },

    "workGroup": { "id": 4, "name": "L1 Support", "updated": true },

    "service": {
      "id": 10, "name": "Email Services",
      "serviceId": 10, "serviceName": "Email Services",
      "updated": true
    },

    "resolutionComment": "Checked mail server logs.",

    "additionalParams": {
      "attribute1": { "fieldid": 101, "data": "Free text value", "updated": true },
      "attribute2": { "fieldid": 102, "data": "2024-01-15", "updated": true },
      "attribute3": { "fieldid": 103, "data": "2024-01-15 14:30", "updated": true },
      "attribute4": { "fieldid": 104, "data": "Option1,Option2", "updated": true },
      "attribute5": { "fieldid": 105, "data": "SelectedOption", "updated": true },
      "attribute6": {
        "fieldid": 106,
        "updated": true,
        "grid": {
          "noOfRow": 2,
          "rows": [
            {
              "attribute1": { "fieldid": 201, "data": "row1-col1-value", "updated": true },
              "attribute2": { "fieldid": 202, "data": "row1-col2-value", "updated": true }
            },
            {
              "attribute1": { "fieldid": 201, "data": "row2-col1-value", "updated": true },
              "attribute2": { "fieldid": 202, "data": "row2-col2-value", "updated": true }
            }
          ]
        }
      }
    }
  }
}

Key Fields — ticket object

Field	Type	Required	Description
`problemId`	Integer	YES	ID of the existing ticket to update.
`title`	String	optional	New ticket title. Updated if provided.
`probDescription`	String	optional	Updated description. Updated if provided.
`owner`	Object	optional	Assign/reassign technician. Requires `"updated": true` to save. Use `userId` (Integer) or `userName` (String).
`approvalManager`	Object	optional	Set approval manager. Requires `"updated": true`. Use `id` or `userName`.
`priority`	Object	optional	Update priority. Requires `"updated": true`. Use `id` or `name`.
`urgency`	Object	optional	Update urgency. Requires `"updated": true`. Use `id` or `name`.
`impact`	Object	optional	Update impact. Requires `"updated": true`. Use `id` or `name`.
`category`	Object	optional	Update category. Requires `"updated": true`. Use `id`/`name` or `categoryId`/`categoryName`.
`subCategory`	Object	optional	Update sub-category. Requires `"updated": true`. Use `id`/`name` or `subcategoryId`/`subcategoryName`.
`service`	Object	optional	Update service. Requires `"updated": true`. Use `id`/`name` or `serviceId`/`serviceName`.
`workGroup`	Object	optional	Update work group. Requires `"updated": true`. Use `id` or `name`.
`location`	Object	optional	Update location. Requires `"updated": true`. Use `id` or `name`.
`department`	Object	optional	Update department. Requires `"updated": true`. Use `id` or `name`.
`derivedField1` / `derivedField2` / `derivedField3`	Object	optional	Update derived fields. Each requires `"updated": true`. Use `id` or `name`.
`source`	Object	optional	Update ticket source. Requires `"updated": true`. Use `id` or `name`.
`resolutionComment`	String	optional	Resolution notes. Updated directly if provided, no `updated` flag needed.
`ccMailId`	String	optional	CC email addresses (comma-separated).
`contactNumber`	String	optional	Requester contact number.
`additionalParams`	Object	optional	Additional fields to update. Each attribute requires `"updated": true` to be saved. Same field-type formats as Create Ticket.

Response

● 200 OK

JSON

{
  "requestType":      "UPDATE_TICKET",
  "requestTime":      "2024-01-15T11:00:00.000Z",
  "responceTime":     "2024-01-15T11:00:01.000Z",
  "integrationLogId": "LOG-002",
  "iteration":        1,
  "problemId":        4521,
  "requestNumber":    "INC-2024-00123"
}

POST /ticket/stateChange Transitions a ticket to a new workflow state — supports normal, assignment, single approval, and multi-approval scenarios ▼

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES

The same /ticket/stateChange endpoint handles four different scenarios driven by which fields you populate inside ticket.ticketStateDTO. All four share the same outer envelope (requestType, ticket.problemId, ticket.currentState).

Scenario 1 — Normal State Change

Move the ticket to a different state with an optional comment. Use for any state transition that does not require approval or owner change.

JSON

{
  "requestType":      "STATE_CHANGE",
  "requestTime":      "2024-01-15T12:00:00.000Z",
  "integrationLogId": "LOG-003",
  "iteration": 0,
  "ticket": {
    "problemId": 4521,

    "currentState": {
      "id": 3, "name": "Resolved",
      "stateId": 3, "stateName": "Resolved"
    },

    "resolutionComment":   "Issue resolved after restarting mail service.",
    "slaviolationComment": "",
    "resolutionCauseId":   2,
    "resolutionDays":      "0",
    "resolutionHours":     "2",
    "resolutionMinutes":   "30",

    "ticketStateDTO": {
      "comment": "Resolved — user confirmed fix.",
      "access":  "Public"
    },

    "additionalParams": {
      "attribute1": { "fieldid": 101, "data": "Free text value" },
      "attribute2": { "fieldid": 102, "data": "2024-01-15" },
      "attribute3": { "fieldid": 103, "data": "2024-01-15 14:30" },
      "attribute4": { "fieldid": 104, "data": "Option1,Option2" },
      "attribute5": { "fieldid": 105, "data": "SelectedOption" },
      "attribute6": {
        "fieldid": 106,
        "grid": {
          "noOfRow": 2,
          "rows": [
            {
              "attribute1": { "fieldid": 201, "data": "row1-col1-value" },
              "attribute2": { "fieldid": 202, "data": "row1-col2-value" }
            },
            {
              "attribute1": { "fieldid": 201, "data": "row2-col1-value" },
              "attribute2": { "fieldid": 202, "data": "row2-col2-value" }
            }
          ]
        }
      }
    }
  }
}

Field	Type	Required	Description
`ticket.problemId`	Integer	YES	Internal ticket ID to transition
`ticket.currentState.id`	Integer	YES	Target state ID to move to
`ticket.currentState.name`	String	optional	Human-readable target state name
`ticket.ticketStateDTO.comment`	String	optional	State-change comment (shown in ticket history)
`ticket.ticketStateDTO.access`	String	optional	Comment visibility: `Public` or `Private`
`ticket.resolutionComment`	String	optional	Resolution notes — typically required when closing a ticket
`ticket.resolutionCauseId`	Integer	optional	Root cause category ID
`ticket.resolutionDays`	String	optional	Days spent on resolution (default `"0"`)
`ticket.resolutionHours`	String	optional	Hours spent on resolution
`ticket.resolutionMinutes`	String	optional	Minutes spent on resolution
`ticket.additionalParams`	Object	optional	Additional fields to update during state change. Same field-type formats as Create Ticket. No `updated` flag required — all provided attributes are saved.

Scenario 2 — Ticket Assignment (Change Owner / Technician)

Assign or re-assign the ticket to a technician by populating ticket.owner. The state can remain the same or change at the same time.

JSON

{
  "requestType":      "STATE_CHANGE",
  "requestTime":      "2024-01-15T12:00:00.000Z",
  "integrationLogId": "LOG-003",
  "iteration": 0,
  "ticket": {
    "problemId": 4521,

    "currentState": {
      "id": 2, "name": "Assigned",
      "stateId": 2, "stateName": "Assigned"
    },

    "owner": {
      "userId":   202,
      "userName": "tech.smith",
      "id":       202,
      "name":     "Tech Smith"
    },

    "ticketStateDTO": {
      "comment": "Assigning to Tech Smith for further investigation.",
      "access":  "Public"
    }
  }
}

Field	Type	Required	Description
`ticket.owner.userId`	Integer	YES	User ID of the technician to assign
`ticket.owner.userName`	String	optional	Username of the assignee
`ticket.ticketStateDTO.comment`	String	optional	Assignment comment logged in ticket history

Scenario 3 — Single Approval State Change

Transitions to an approval state and designates one approval manager. Pass the manager via userId (Integer) or user (login username String) — both are resolved to the same user internally.

JSON

{
  "requestType":      "STATE_CHANGE",
  "requestTime":      "2024-01-15T12:00:00.000Z",
  "integrationLogId": "LOG-003",
  "iteration": 0,
  "ticket": {
    "problemId": 4521,

    "currentState": {
      "id": 5, "name": "Pending Approval",
      "stateId": 5, "stateName": "Pending Approval"
    },

    "ticketStateDTO": {
      "comment": "Awaiting manager approval before closure.",
      "access":  "Public",

      "userId":  303
    }
  }
}

Field	Type	Required	Description
`ticket.ticketStateDTO.userId`	Integer	YES*	User ID of the approval manager. Takes priority over `user`.
`ticket.ticketStateDTO.user`	String	YES*	Login username of the approval manager. Used if `userId` is not provided.
* Provide either `userId` or `user` — at least one is required.
`ticket.ticketStateDTO.comment`	String	optional	Comment to log when entering approval state

Scenario 4 — Multi-Approval State Change

Transitions to an approval state with multiple approval managers. Each approvalManager1…approvalManager10 field must contain the manager's login username (not the numeric user ID) — the server resolves the username to the user ID internally.

⚠ approvalManager1…10 must be login usernames, not user IDs. The server calls userService.getUser(username) on each value. Passing a numeric ID string will fail to resolve the user.

JSON

{
  "requestType":      "STATE_CHANGE",
  "requestTime":      "2024-01-15T12:00:00.000Z",
  "integrationLogId": "LOG-003",
  "iteration": 0,
  "ticket": {
    "problemId": 4521,

    "currentState": {
      "id": 5, "name": "Pending Approval",
      "stateId": 5, "stateName": "Pending Approval"
    },

    "ticketStateDTO": {
      "comment":            "Requires approval from 3 managers.",
      "access":             "Public",

      "approvalManager1":   "john.manager",
      "approvalManager2":   "sarah.lead",
      "approvalManager3":   "tom.director",

      "noOfApprovals":      3,
      "minNoOfApprovals":   2,
      "minNoOfRejections":  1
    }
  }
}

Field	Type	Required	Description
`ticket.ticketStateDTO.approvalManager1` …`approvalManager10`	String	YES	Login username of each approval manager. Populate sequentially from `approvalManager1`. Must not be a numeric ID.
`ticket.ticketStateDTO.noOfApprovals`	Integer	optional	Total number of approval manager slots. Defaults to the value configured on the state in the project settings if omitted.
`ticket.ticketStateDTO.minNoOfApprovals`	Integer	optional	Minimum approvals needed to advance the ticket. Defaults to project-configured value.
`ticket.ticketStateDTO.minNoOfRejections`	Integer	optional	Minimum rejections needed to reject the ticket. Defaults to project-configured value.
`ticket.ticketStateDTO.comment`	String	optional	Comment logged when entering the approval state

ticketStateDTO — Full Field Reference

Field	Type	Description
`comment`	String	State-change comment displayed in ticket history
`user`	String	Login username used to resolve the approval manager in single-approval scenarios
`userId`	Integer	User ID used to resolve the approval manager in single-approval scenarios (takes priority over `user`)
`access`	String	Comment visibility: `Public` or `Private`
`resolutionDays`	String	Days component of time-to-resolve
`resolutionHours`	String	Hours component of time-to-resolve
`resolutionMinutes`	String	Minutes component of time-to-resolve
`approvalManager1…10`	String	Login username for each multi-approval manager slot (up to 10). Resolved to user ID server-side.
`noOfApprovals`	Integer	Total number of approval manager slots in use
`minNoOfApprovals`	Integer	Minimum approvals required to advance the ticket
`minNoOfRejections`	Integer	Minimum rejections required to reject the ticket

additionalParams — Field Type Reference (State Change)

additionalParams can be included at the ticket level in any state-change scenario to update additional fields as part of the transition. No updated flag is required — all provided attributes are saved. Field type formats are identical to the Create Ticket API.

Field Type	Type ID	`data` Format	Example
Text Box	1	Plain string. Must match configured regex/mask if set.	`"data": "Some text"`
Select Box (Dropdown)	2	Exact option value string from the configured list.	`"data": "Hardware"`
Date And Time Field	3	`yyyy-MM-dd HH:mm` (24-hour)	`"data": "2024-01-15 14:30"`
Text Area	4	Multi-line plain text string.	`"data": "Notes here"`
Radio Button	5	Exact option value string.	`"data": "Yes"`
Multi Select Box	6	Comma-separated option values. No spaces around comma.	`"data": "Option1,Option2"`
Check Box (YES/NO)	7	`"true"` or `"false"` as string.	`"data": "true"`
Title / Sub-Title / Label / HTML Content	8, 9, 10, 17	Display-only. Omit entirely.	—
Searchable Multi Select Box	12	Comma-separated option values.	`"data": "Tag1,Tag2"`
Grid Control / Calendar Event	13, 18	No `data` field. Use `grid` object with `noOfRow` and `rows` array.	See grid example in Scenario 1
File Upload	14	Cannot be submitted inline. Use attachment upload endpoint after ticket creation.	—
Date Field	15	`yyyy-MM-dd`	`"data": "2024-01-15"`
Hyperlink	20	Valid URL string.	`"data": "https://example.com"`
Time Field	21	`HH:mm` (24-hour)	`"data": "09:30"`
Editable Select Box	22	Existing option or free-text string.	`"data": "Custom Value"`
Editable Multi Select Box	23	Comma-separated values.	`"data": "Value1,Value2"`

Response (all scenarios)

● 200 OK

JSON

{
  "requestType":      "STATE_CHANGE",
  "requestTime":      "2024-01-15T12:00:00.000Z",
  "responceTime":     "2024-01-15T12:00:01.200Z",
  "integrationLogId": "LOG-003",
  "iteration":        0,
  "problemId":        4521,
  "requestNumber":    "INC-2024-00123"
}

Retrieve Tickets

GET /ticket/get/{id}/id Fetch full ticket details by internal problem ID ▼

Headers

Header	Required
`int-log-id`	YES
`X-API-KEY`	YES
`TOKEN`	YES

Path Parameters

Parameter	Type	Description
`id`	Integer	Internal ticket problem ID

Query Parameters

Parameter	Type	Default	Description
`history`	Boolean	false	Set `true` to include full state-change history

Example Request

HTTP

GET /ticket/get/4521/id?history=true
int-log-id: LOG-004
X-API-KEY: your-api-key
TOKEN: your-token

Response

● 200 OK

JSON

{
  "requestType":      "GET_TICKET",
  "responceTime":     "2024-01-15T12:05:00.000Z",
  "integrationLogId": "LOG-004",
  "problemId":        4521,
  "requestNumber":    "INC-2024-00123",
  "ticket": {
    "problemId":       4521,
    "requestId":       "INC-2024-00123",
    "title":           "Email not working",
    "probDescription": "Unable to send or receive emails.",
    "project":         { "id": 1,  "name": "IT Support" },
    "service":         { "id": 10, "name": "Email Services" },
    "currentState":    { "id": 3,  "name": "In Progress" },
    "submittedBy":     { "userId": 101, "userName": "john.doe" },
    "owner":           { "userId": 202, "userName": "tech.smith" },
    "category":        { "id": 5,  "name": "Software" },
    "subCategory":     { "id": 12, "name": "Email Client" },
    "priority":        { "id": 2,  "name": "High" },
    "urgency":         { "id": 1,  "name": "Critical" },
    "impact":          { "id": 1,  "name": "High" },
    "creationTime":    "2024-01-15T10:30:01.000Z",
    "lastOperatedTime":"2024-01-15T12:00:01.000Z",
    "servicerequestHistory": [ "..." ]
  }
}

GET /ticket/get/{id}/requestId/{projectName}/projectName Fetch ticket by request number and project name ▼

Headers

Header	Required
`int-log-id`	YES
`X-API-KEY`	YES
`TOKEN`	YES

Path Parameters

Parameter	Type	Description
`id`	String	Request number (e.g. `INC-2024-00123`)
`projectName`	String	Exact project name (URL-encoded if it contains spaces)

Query Parameters

Parameter	Type	Default	Description
`history`	Boolean	false	Include state-change history

Example Request

HTTP

GET /ticket/get/INC-2024-00123/requestId/IT%20Support/projectName?history=false

Response

● 200 OK

Same response structure as Get Ticket by ID.

POST /ticket/find Search tickets within a single project with filters & pagination ▼

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES
`X-API-KEY`	Your API key	YES
`TOKEN`	Your auth token	YES

Request Body — Single Project

JSON

{
  "pageNumber": 1,
  "pageSize":   30,

  "project": {
    "id": 1, "name": "IT Support",
    "projectId": 1, "projectName": "IT Support"
  },

  "service": [
    { "id": 10, "name": "Email Services", "serviceId": 10, "serviceName": "Email Services" }
  ],

  "states": [
    { "id": 1, "name": "Open",        "stateId": 1, "stateName": "Open" },
    { "id": 3, "name": "In Progress", "stateId": 3, "stateName": "In Progress" }
  ],

  "stateCategory": [
    { "id": 1, "name": "Active" }
  ],

  "category": [
    { "id": 5, "name": "Hardware", "categoryId": 5, "categoryName": "Hardware" }
  ],

  "subCategory": [
    { "id": 12, "name": "Laptop", "subcategoryId": 12, "subcategoryName": "Laptop" }
  ],

  "location": [
    { "id": 3, "name": "Chennai HQ" }
  ],

  "department": [
    { "id": 7, "name": "Finance" }
  ],

  "priority": [
    { "id": 2, "name": "High" }
  ],

  "urgency": [
    { "id": 1, "name": "Critical" }
  ],

  "impact": [
    { "id": 1, "name": "High" }
  ],

  "derivedField1": [
    { "id": 8, "name": "Region", "derivedFieldId": 8, "derivedFieldName": "Region" }
  ],
  "derivedField2": [],
  "derivedField3": [],

  "workGroups": [
    { "id": 4, "name": "L1 Support" }
  ],

  "ticketState":           "Open",
  "submittedBy":           "john.doe",
  "approvalManager":       "",
  "owner":                 "tech.smith",
  "requestNo":             "",
  "title":                 "email",
  "alternativeEmail":      "",
  "creationStartTime":     "2024-01-01T00:00:00.000Z",
  "creationEndTime":       "2024-01-31T23:59:59.000Z",
  "lastOperatedStartTime": null,
  "lastOperatedEndTime":   null,
  "details":               false,
  "orderBy":               "creationTime",
  "orderByDirection":      "DESC",
  "sortOnField":           "",
  "assetId":               null,
  "assetNumber":           null,
  "assetItemTypeId":       null,
  "siteId":                1,

  "additionalParams": {
    "attribute1": { "fieldid": 101, "data": "Hardware" },
    "attribute2": { "fieldid": 102, "data": "Laptop" },
    "attribute3": { "fieldid": 103, "data": "Critical" }
  }
}

Request Body — Multiple Projects

Replace project (single object) with projects (array). When projects is present, the API automatically routes to multi-project search. Note: additionalParams filtering is not supported in multi-project mode.

JSON

{
  "pageNumber": 1,
  "pageSize":   30,

  "projects": [
    { "id": 1, "name": "IT Support",  "projectId": 1, "projectName": "IT Support" },
    { "id": 2, "name": "HR Support",  "projectId": 2, "projectName": "HR Support" },
    { "id": 3, "name": "Facilities",  "projectId": 3, "projectName": "Facilities" }
  ],

  "service": [
    { "id": 10, "name": "Email Services", "serviceId": 10, "serviceName": "Email Services" }
  ],

  "states": [
    { "id": 1, "name": "Open",        "stateId": 1, "stateName": "Open" },
    { "id": 3, "name": "In Progress", "stateId": 3, "stateName": "In Progress" }
  ],

  "stateCategory": [
    { "id": 1, "name": "Active" }
  ],

  "category": [
    { "id": 5, "name": "Hardware", "categoryId": 5, "categoryName": "Hardware" }
  ],

  "subCategory": [
    { "id": 12, "name": "Laptop", "subcategoryId": 12, "subcategoryName": "Laptop" }
  ],

  "location": [
    { "id": 3, "name": "Chennai HQ" }
  ],

  "department": [
    { "id": 7, "name": "Finance" }
  ],

  "priority": [
    { "id": 2, "name": "High" }
  ],

  "urgency": [
    { "id": 1, "name": "Critical" }
  ],

  "impact": [
    { "id": 1, "name": "High" }
  ],

  "derivedField1": [
    { "id": 8, "name": "Region", "derivedFieldId": 8, "derivedFieldName": "Region" }
  ],
  "derivedField2": [],
  "derivedField3": [],

  "workGroups": [
    { "id": 4, "name": "L1 Support" }
  ],

  "ticketState":           "Open",
  "submittedBy":           "john.doe",
  "approvalManager":       "",
  "owner":                 "tech.smith",
  "requestNo":             "",
  "title":                 "email",
  "alternativeEmail":      "",
  "creationStartTime":     "2024-01-01T00:00:00.000Z",
  "creationEndTime":       "2024-01-31T23:59:59.000Z",
  "lastOperatedStartTime": null,
  "lastOperatedEndTime":   null,
  "details":               false,
  "orderBy":               "creationTime",
  "orderByDirection":      "DESC",
  "sortOnField":           "",
  "assetId":               null,
  "assetNumber":           null,
  "assetItemTypeId":       null,
  "siteId":                1
}

Search Fields Reference

💡 Multi-project support: /find also accepts a projects array (same as /findAll). When projects is provided, the API automatically routes to the multi-project search path — no need to call /findAll separately.

Field	Type	Description
`pageNumber`	Integer	Page number, starts at 1 (default: 1)
`pageSize`	Integer	Results per page — default 30, max 100
`project`	Object `{id}`	REQUIRED* — single project to search within. Use `projects` array for multi-project search.
`projects`	Array of `{id}`	Search across multiple projects simultaneously. When provided, `project` (single) is not required.
`ticketState`	String	`ALL`, `Open`, or `Closed`. Defaults to `Open` if no state filter is set.
`states`	Array	Filter by specific state IDs
`stateCategory`	Array	Filter by state category IDs
`submittedBy`	String	Username / login ID of the requester
`owner`	String	Username of the assigned technician
`requestNo`	String	Filter by exact request number
`title`	String	Keyword search on ticket title
`creationStartTime`	Date (ISO 8601)	Filter tickets created after this time
`creationEndTime`	Date (ISO 8601)	Filter tickets created before this time
`lastOperatedStartTime`	Date (ISO 8601)	Filter by last activity start window
`lastOperatedEndTime`	Date (ISO 8601)	Filter by last activity end window
`approvalManager`	String	Username of the approval manager to filter on
`alternativeEmail`	String	Alternative email address on the ticket
`details`	Boolean	`true` = return full ticket objects; `false` (default) = return summary list
`orderBy`	String	Column to sort by — valid values: `creationTime` (default), `lastOperatedTime`, `problemId`, `requestId`, `title`. Value is injected directly into SQL — use only these exact names.
`orderByDirection`	String	`DESC` (default) or `ASC`
`sortOnField`	String	Secondary sort field (optional; leave empty string if unused)
`assetId`	Integer	Filter tickets linked to a specific asset by its internal ID
`assetNumber`	String	Filter by linked asset number — requires `assetItemTypeId` when set; omitting `assetItemTypeId` throws a validation error
`assetItemTypeId`	Integer	Asset item type ID — required when `assetNumber` is provided
`siteId`	Integer	Site scope for the search (defaults to `1`)
`additionalParams`	AdditionalParams	Filter by custom additional fields — see Additional Fields Search section below. Not supported in multi-project mode.

Date / Time Field Preparation

📅 How to prepare creationStartTime, creationEndTime, lastOperatedStartTime, lastOperatedEndTime

These fields are deserialized by Jackson as a Java Date. Pass the value as an ISO 8601 UTC string in the format "yyyy-MM-ddTHH:mm:ss.SSSZ" — for example "2024-01-01T00:00:00.000Z".

The trailing Z denotes UTC (zero offset). If your local timezone differs from the server timezone, convert to UTC before building the string so the filter window is correct.

JavaScript / TypeScript example:

JavaScript

// Start of day in local time → converted to UTC ISO string
const startOfDay = new Date(2024, 0, 1, 0, 0, 0, 0);      // Jan 1 2024 00:00 local
const endOfDay   = new Date(2024, 0, 31, 23, 59, 59, 999); // Jan 31 2024 23:59:59.999 local

const body = {
  pageNumber: 1,
  pageSize:   30,
  project: { id: 1 },
  creationStartTime: startOfDay.toISOString(),  // "2024-01-01T00:00:00.000Z" (if local is UTC)
  creationEndTime:   endOfDay.toISOString(),    // "2024-01-31T23:59:59.999Z"
};

// If you want a fixed UTC range regardless of local timezone:
const utcStart = "2024-01-01T00:00:00.000Z";
const utcEnd   = "2024-01-31T23:59:59.999Z";

Field	Format	Notes
`creationStartTime`	`"yyyy-MM-ddTHH:mm:ss.SSSZ"`	Inclusive lower bound on ticket creation time
`creationEndTime`	`"yyyy-MM-ddTHH:mm:ss.SSSZ"`	Inclusive upper bound — must be > `creationStartTime` or server throws an error
`lastOperatedStartTime`	`"yyyy-MM-ddTHH:mm:ss.SSSZ"`	Lower bound on last activity time
`lastOperatedEndTime`	`"yyyy-MM-ddTHH:mm:ss.SSSZ"`	Upper bound on last activity time

Additional Fields Search (additionalParams)

⚠️ When additionalParams is present in the request, the search switches to a dedicated additional-field query path. The system performs a LEFT JOIN against the additional params table for each populated attribute and applies an exact match (Data = :value). Only works with a single project (not multi-project). Grid fields and multi-value types are not supported in the search path.

The additionalParams object contains named slots attribute1 through attribute50+. Each attribute maps to a configured custom field on the project. Populate only the attributes you want to filter on. Use only the fieldid and data fields — the grid field is ignored in search.

JSON — additionalParams search example

{
  "pageNumber": 1,
  "pageSize": 30,
  "project": { "id": 1 },
  "additionalParams": {
    "attribute1": { "fieldid": 101, "data": "Hardware" },
    "attribute3": { "fieldid": 103, "data": "Critical" }
  }
}

Field	Type	Description
`attribute1` … `attribute50`	Object	Named slot for each custom additional field. Omit slots you don't want to filter on.
`attribute{n}.fieldid`	Integer	The configured field ID for this additional field on the project
`attribute{n}.data`	String	The value to match — exact string match against the stored `Data` column

Supported Field Types for additionalParams Search

Only field types that store a single plain string value in the Data column are searchable. Grid-based and multi-select types store data differently and are not supported in the find query.

Type ID	Field Type	How to pass `data`	Searchable?
1	TextBox	Any plain string — exact match	YES
2	SelectBox	The exact option value as stored (e.g. `"Hardware"`)	YES
3	DateAndTimeField	`"yyyy-MM-dd HH:mm"` — exact match on stored string	YES
4	TextArea	Any plain string — exact match	YES
5	RadioButton	The selected option value	YES
7	CheckBoxYESNO	`"YES"` or `"NO"`	YES
15	DateField	`"yyyy-MM-dd"` — exact match on stored string	YES
21	TimeField	`"HH:mm"` — exact match on stored string	YES
22	EditableSelectBox	The typed/selected value string	YES
6	MultiSelectBox	Stores comma-separated values — single exact match not reliable	NO
12	SearchableMultiSelectBox	Multi-value — not supported in find	NO
23	EditableMultiSelectBox	Multi-value — not supported in find	NO
13	GridControl	Grid data — not supported in find	NO
16	StaticGrid	Grid data — not supported in find	NO
14	FileUpload	File reference — not applicable for search	NO

The field slot names (attribute1, attribute2, …) correspond to the additional field configuration on the project. Contact your SapphireIMS admin to get the correct fieldid and slot mapping for your project.

Response

● 200 OK

JSON

{
  "totalCount": 142,
  "pageNumber":  1,
  "pageSize":   30,
  "tickets": [
    {
      "problemId":    4521,
      "requestId":    "INC-2024-00123",
      "title":        "Email not working",
      "currentState": { "id": 3, "name": "In Progress" },
      "submittedBy":  { "userId": 101 },
      "creationTime": "2024-01-15T10:30:01.000Z"
    }
  ]
}

GET /ticket/findAll Search tickets across multiple projects simultaneously ▼

⚠️ Uses GET method but accepts a JSON request body. Some HTTP clients require explicit configuration to send a body with GET requests.

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES
`X-API-KEY`	Your API key	YES
`TOKEN`	Your auth token	YES

Request Body

Use projects (array) instead of project (single object). The projects array must not be empty.

JSON

{
  "pageNumber": 1,
  "pageSize":   30,
  "projects":   [{ "id": 1 }, { "id": 2 }, { "id": 3 }],
  "ticketState": "Open",
  "title":       "email",
  "submittedBy": "john.doe"
}

Response

● 200 OK

Same response structure as Search Tickets (/find).

Comments

POST /ticket/comment Add a comment or note to an existing ticket ▼

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES
`X-API-KEY`	Your API key	YES
`TOKEN`	Your auth token	YES

Request Body

JSON

{
  "problemId":    4521,
  "requestId":    "INC-2024-00123",
  "projectName":  "IT Support",
  "projectId":    1,
  "userId":       101,
  "userName":     "john.doe",
  "emailAddress": "john.doe@example.com",
  "cellNo":       "9876543210",
  "comment":      "Called user — confirmed issue is reproducible.",
  "accessType":   1,
  "title":        "Follow-up note",
  "latitude":     "12.9716",
  "longitude":    "77.5946"
}

Ticket Identification

Provide one of the following to identify the ticket:
• problemId — preferred; direct internal ID lookup.
• requestId + (projectId or projectName) — used when problemId is unknown.

User Identification

The server resolves the commenter using the first matching identifier in this priority order. Provide at least one:

1. userId — direct lookup by internal user ID
2. userName — lookup by login name / username
3. cellNo — lookup by registered mobile number
4. emailAddress — lookup by registered email address

If none of the provided identifiers resolve to a known user, the server returns a validation error.

Key Fields

Field	Type	Required	Description
`problemId`	Integer	YES*	Ticket's internal numeric ID. Takes priority over `requestId`.
`requestId`	String	YES*	Ticket request number (e.g. `INC-2024-00123`). Used when `problemId` is not provided.
`projectId`	Integer	optional	Project ID — required when looking up ticket by `requestId`
`projectName`	String	optional	Project name — used as fallback if `projectId` is not provided
`userId`	Integer	optional	Internal user ID of the commenter (highest-priority user lookup)
`userName`	String	optional	Login name of the commenter
`emailAddress`	String	optional	Registered email address — used to resolve user if `userId`, `userName`, and `cellNo` are all absent or unresolvable
`cellNo`	String	optional	Registered mobile number — used to resolve user if `userId` and `userName` are absent or unresolvable
`comment`	String	YES	Comment body text — mandatory; empty string throws a validation error
`accessType`	Integer	optional	`1` = Public (default), `2` = Private/Internal
`title`	String	optional	Enclosure heading — defaults to `"Comment Enclosure"` if not provided
`latitude`	String	optional	GPS latitude — stored in history record (e.g. from a mobile client)
`longitude`	String	optional	GPS longitude — stored in history record
`stateId`	Integer	—	Server-overridden. Always set to the ticket's current state; any value you pass is ignored.
`date`	Date	—	Server-overridden. Always set to the current server time; any value you pass is ignored.

Response

● 200 OK

JSON

"Comment added successfully"

Attachments

POST /ticket/upload Upload a file attachment using multipart form data ▼

Headers

Header	Value	Required
`Content-Type`	multipart/form-data	YES

Form Fields

Field	Type	Required	Description
`problemId`	Integer	YES*	Ticket internal ID
`requestNo`	String	YES*	Request number (alternative to problemId)
`project`	String	YES*	Project name (required with requestNo)
`userId`	String	YES	User ID performing the upload
`file`	File	YES	The file to upload
`stataeId`	String	optional	State ID context
`comment`	String	optional	Comment to attach alongside the file
`access`	Byte	optional	`1` = public, `2` = private

Response

● 200 OK

TEXT

Successfully uploaded!

POST /ticket/uploadAttachment Upload a file as raw binary octet-stream ▼

Useful for programmatic / server-to-server uploads where multipart is not practical. Send the raw file bytes as the request body.

Headers

Header	Value	Required	Description
`Content-Type`	application/octet-stream	YES	Binary content type
`FileName`	e.g. report.pdf	YES	Original file name

Query Parameters

Parameter	Type	Default	Required	Description
`problemId`	Integer	0	YES*	Ticket internal ID
`requestNo`	String	—	YES*	Request number (if no problemId)
`project`	String	—	YES*	Project name (required with requestNo)
`userId`	String	1	optional	User ID
`stateId`	String	0	optional	State context
`comment`	String	""	optional	Comment with file
`fieldId`	String	""	optional	Additional field ID
`access`	Byte	1	optional	`1` = public, `2` = private

Example Request

HTTP

POST /ticket/uploadAttachment?problemId=4521&userId=101&stateId=3
Content-Type: application/octet-stream
FileName: incident-report.pdf

<binary file content>

Response

● 200 OK

TEXT

Successfully uploaded!

POST /ticket/download Download a file attachment using ticket context ▼

Headers

Header	Value	Required
`Content-Type`	multipart/form-data	YES

Form Fields

Field	Type	Required	Description
`problemId`	Integer	YES	Ticket internal ID
`requestNo`	String	optional	Request number
`project`	String	optional	Project name
`userId`	Integer	optional	User ID
`stateId`	Integer	optional	State ID

Response

● 200 OK

Binary file stream with Content-Type and Content-Disposition: attachment; filename="..." headers set appropriately.

GET /ticket/downloadAttachment Download a specific attachment by file name ▼

Query Parameters

Parameter	Type	Required	Description
`fileName`	String	YES	System-stored (internal) file name
`fileNameOriginal`	String	YES	Original file name to present to the user for download

Example Request

HTTP

GET /ticket/downloadAttachment?fileName=a1b2c3-uuid.pdf&fileNameOriginal=invoice.pdf

Response

● 200 OK

Binary file stream.

POST /ticket/getAttachment List all attachments for a ticket ▼

Headers

Header	Value	Required
`Content-Type`	multipart/form-data	YES

Form Fields

Field	Type	Required	Description
`problemId`	Integer	YES	Ticket internal ID
`requestNo`	String	optional	Request number
`project`	String	optional	Project name
`userId`	Integer	optional	User ID
`stateId`	Integer	optional	State ID

Response

● 200 OK

JSON

[
  {
    "fileName":         "a1b2c3-uuid.pdf",
    "fileNameOriginal": "incident-report.pdf",
    "uploadedBy":       "john.doe",
    "uploadedOn":       "2024-01-15T10:45:00.000Z",
    "access":           1
  }
]

Workflow — Next Possible States

POST /ticket/nextStates Get valid next states (multipart form) ▼

Headers

Header	Value	Required
`Content-Type`	multipart/form-data	YES

Form Fields

Field	Type	Required	Description
`problemId`	Integer	YES	Ticket internal ID
`requestNo`	String	optional	Request number
`project`	String	optional	Project name
`userId`	Integer	optional	User ID (used for role-based state filtering)
`stateId`	Integer	optional	Current state ID
`stateName`	String	optional	Current state name
`loginId`	String	optional	Login ID of the requesting user

Response

● 200 OK

JSON

{
  "states": [
    { "id": 3, "name": "In Progress" },
    { "id": 5, "name": "Pending" },
    { "id": 8, "name": "Resolved" }
  ]
}

POST /ticket/nextPossibleStates Get valid next states (JSON body) ▼

Same functionality as /nextStates but accepts a JSON body — preferred for API integrations.

Headers

Header	Value	Required
`Content-Type`	application/json	YES

Request Body

JSON

{
  "problemId":  4521,
  "requestNo":  "INC-2024-00123",
  "project":    "IT Support",
  "userId":     101,
  "stateId":    2,
  "stateName":  "Open",
  "loginId":    "john.doe"
}

Response

● 200 OK

Same response structure as /nextStates.

Common Object Schemas

MinDTO Pattern — id OR name

All reference objects accept either the numeric id or the string name — you don't need both. Each type also exposes its own specific field name aliases as shown below.

💡 You can pass either the ID or the name for any reference object. The API resolves the record by ID first; if ID is absent or null, it falls back to name lookup.

Object	ID field(s)	Name field(s)	Example
`project`	`id` or `projectId`	`name` or `projectName`	`{"projectId": 1}` or `{"projectName": "IT Support"}`
`service`	`id` or `serviceId`	`name` or `serviceName`	`{"serviceId": 10}` or `{"serviceName": "Email Services"}`
`currentState` / `states`	`id` or `stateId`	`name` or `stateName`	`{"stateId": 3}` or `{"stateName": "In Progress"}`
`category`	`id` or `categoryId`	`name` or `categoryName`	`{"categoryId": 5}` or `{"categoryName": "Hardware"}`
`subCategory`	`id` or `subcategoryId`	`name` or `subcategoryName`	`{"subcategoryId": 12}` or `{"subcategoryName": "Laptop"}`
`priority` / `urgency` / `impact`	`id`	`name`	`{"id": 2}` or `{"name": "High"}`
`location`	`id`	`name`	`{"id": 3}` or `{"name": "Chennai HQ"}`
`department`	`id`	`name`	`{"id": 7}` or `{"name": "Finance"}`
`workGroup`	`id`	`name`	`{"id": 4}` or `{"name": "L1 Support"}`
`derivedField1/2/3`	`id` or `derivedFieldId`	`name` or `derivedFieldName`	`{"derivedFieldId": 8}` or `{"derivedFieldName": "Region"}`
`source`	`id`	`name`	`{"id": 1}` or `{"name": "Portal"}`

TicketRequest Wrapper

JSON

{
  "requestType":      "String  — e.g. CREATE_TICKET, UPDATE_TICKET, STATE_CHANGE",
  "requestTime":      "ISO-8601 Date — time the request was sent",
  "integrationLogId": "String  — your log/trace ID",
  "iteration":        0,
  "ticket":           { "...TicketDTO fields..." }
}

TicketResponse Wrapper

JSON

{
  "requestType":      "String",
  "requestTime":      "ISO-8601 Date",
  "responceTime":     "ISO-8601 Date",
  "integrationLogId": "String",
  "iteration":        0,
  "problemId":        12345,
  "requestNumber":    "INC-2024-00123",
  "ticket":           { "...TicketDTO fields (GET responses only)..." }
}

TicketDTO — Key Fields Reference

Field	Type	Description
`problemId`	Integer	Internal unique ticket ID
`requestId`	String	Human-readable request number
`title`	String	Ticket subject
`probDescription`	String	Full description of the issue
`project`	ProjectMinDTO	`{ id, name }`
`service`	ServiceMinDTO	`{ id, name }`
`currentState`	SdStatesMasterDTO	Current workflow state
`submittedBy`	UserDetailsDTO	Requester user object
`owner`	UserDTO	Assigned technician
`approvalManager`	UserDTO	Approval manager
`workGroup`	WorkGroupMinDTO	Assigned work group / team
`category`	CategoryMinDTO	Issue category
`subCategory`	SubCategoryMinDTO	Issue sub-category
`location`	LocationMinDTO	Physical location
`department`	DepartmentMinDTO	Requester department
`priority`	UipMinDTO	Priority level
`urgency`	UipMinDTO	Urgency level
`impact`	UipMinDTO	Impact level
`creationTime`	Date	Ticket creation timestamp
`lastOperatedTime`	Date	Last activity timestamp
`resolutionComment`	String	Resolution notes
`resolutionCauseId`	Integer	Root cause ID
`ccMailId`	String	CC email list
`attachments`	Array	List of attached files
`additionalParams`	Object	Custom additional fields key-value map
`servicerequestHistory`	Array	State change history (when `history=true`)
`latitude` / `longitude`	String	Geo-coordinates
`iteration`	Integer	Retry/version counter for idempotency

Error Codes

HTTP Status	Error Type	Condition
200 OK	—	Request processed successfully
400 Bad Request	ValidationException	Missing required fields, invalid pagination (pageSize > 100), invalid date ranges, missing `assetItemTypeId` when `assetNumber` is provided
400 Bad Request	DomainException	Business rule violation, e.g. invalid state transition or referenced ID not found
404 Not Found	TicketException	Ticket not found for the given ID or request number
500 Internal Error	Exception	Unexpected server-side error — check integration logs using the `int-log-id`

📋 Always include a unique int-log-id in every request. This ID is logged server-side and is essential for diagnosing errors with the SapphireIMS support team.

All User API endpoints use the same authentication headers. An additional TENANT-NAME header is required in multi-tenant (server) deployments.

Header	Type	Required	Description
`int-log-id`	String	OPTIONAL	Integration log identifier for tracing
`X-API-KEY`	String	REQUIRED	API key credential
`TOKEN`	String	REQUIRED	Authentication token
`TENANT-NAME`	String	CONDITIONAL	Required in multi-tenant server deployments; omit for single-tenant
`Content-Type`	String	REQUIRED	`application/json`

User Management

POST /user/add Create a new user account ▼

Request Body (User)

{
  "userName": "john.doe",
  "password": "SecureP@ss123",
  "fullName": "John Doe",
  "emailAddress": "john.doe@company.com",
  "accessType": "END_USER",
  "cellNo": "+919876543210",
  "telephoneNumber": "04422334455",
  "employeeId": "EMP-1001",
  "department": "IT",
  "location": "Head Office",
  "immediateManager": "jane.smith",
  "manager": "jane.smith",
  "isManager": false,
  "loginAllowed": true,
  "tfaEnabled": false,
  "uiInterface": 0,
  "preferredContactMethod": 1,
  "domainName": "CORP",
  "ouname": "OU=IT,DC=corp,DC=com",
  "server": "ldap.corp.com",
  "goc": "GOC-001",
  "wing": "Engineering",
  "city": "Chennai",
  "addtionalFileds": {
    "costCenter": "CC-001",
    "grade": "L3"
  }
}

User Object — Key Fields

Field	Type	Required	Description
`userName`	String	REQUIRED	Login username (unique)
`password`	String	REQUIRED	Initial password
`fullName`	String	REQUIRED	Display name of the user
`accessType`	String	REQUIRED	User role — e.g. `END_USER`, `TECHNICIAN`, `ADMIN`
`emailAddress`	String	OPTIONAL	Primary email address
`cellNo`	String	OPTIONAL	Mobile number
`telephoneNumber`	String	OPTIONAL	Landline / office number
`employeeId`	String	OPTIONAL	HR employee ID
`department`	String	OPTIONAL	Department name
`location`	String	OPTIONAL	Office / site location name
`immediateManager`	String	OPTIONAL	Immediate manager's username
`isManager`	Boolean	OPTIONAL	Whether this user is a manager
`loginAllowed`	Boolean	OPTIONAL	Whether login is permitted
`tfaEnabled`	Boolean	OPTIONAL	Enable two-factor authentication
`uiInterface`	Integer	OPTIONAL	UI mode — `0` = Standard, `1` = Classic
`preferredContactMethod`	Integer	OPTIONAL	`1` = Email, `2` = SMS, `3` = Phone
`domainName`	String	OPTIONAL	AD domain name
`ouname`	String	OPTIONAL	Active Directory Organizational Unit
`server`	String	OPTIONAL	AD server hostname
`addtionalFileds`	Map<String,String>	OPTIONAL	Arbitrary key-value pairs for custom user attributes
`fcmToken`	String	OPTIONAL	Firebase Cloud Messaging token for push notifications

Response Body

201 Created

{
  "userId": 105,
  "userName": "john.doe",
  "fullName": "John Doe",
  "emailAddress": "john.doe@company.com",
  "accessType": "END_USER",
  "loginAllowed": true,
  "tfaEnabled": false,
  "creationTime": "2024-06-01 10:00:00"
}

POST /user/update Update an existing user's profile ▼

Same request body shape as Create User. Include userId or userName to identify the user. Only fields provided will be updated.

Request Body

{
  "userId": 105,
  "userName": "john.doe",
  "fullName": "John A. Doe",
  "emailAddress": "john.a.doe@company.com",
  "department": "Infrastructure",
  "telephoneNumber": "04422334456"
}

Response

204 No Content

POST /user/delete/{userName} Soft-delete (deactivate) a user account ▼

Path Parameters

Parameter	Type	Required	Description
`userName`	String	REQUIRED	Login username to delete. Supports dots and special chars (`:.+` pattern).

Example Request

POST /user/delete/john.doe
X-API-KEY: your-api-key
TOKEN: your-token

Response

204 No Content

GET /user/get/{userName} Get full profile of a user by username ▼

Path Parameters

Parameter	Type	Required	Description
`userName`	String	REQUIRED	Login username. Supports dots and special chars.

Example Request

GET /user/get/john.doe
X-API-KEY: your-api-key
TOKEN: your-token

Response Body

{
  "userId": 105,
  "userName": "john.doe",
  "fullName": "John Doe",
  "emailAddress": "john.doe@company.com",
  "accessType": "END_USER",
  "department": "IT",
  "location": "Head Office",
  "employeeId": "EMP-1001",
  "cellNo": "+919876543210",
  "telephoneNumber": "04422334455",
  "isManager": false,
  "loginAllowed": true,
  "tfaEnabled": false,
  "domainName": "CORP",
  "creationTime": "2024-06-01 10:00:00",
  "lastLoginTime": "2024-06-20 09:15:00",
  "recentLoginTime": "2024-06-24 08:30:00",
  "isDeleted": false
}

POST /user/find Search and filter users with pagination ▼

Headers

Header	Value	Required
`Content-Type`	application/json	YES
`int-log-id`	Your log ID string	YES
`X-API-KEY`	Your API key	YES
`TOKEN`	Your auth token	YES

Request Body

All fields are optional filters. Omit any field you do not want to filter on. All string filters use exact match — no wildcards or partial matching. Filters are combined with AND. userAdditionalFields is not supported in this search.

JSON

{
  "pageNumber":      1,
  "pageSize":        30,

  "userId":          101,
  "userName":        "john.doe",
  "fullName":        "John Doe",
  "emailAddress":    "john.doe@company.com",
  "employeeId":      "EMP-1001",
  "cellNo":          "9876543210",
  "countryCode":     "+91",
  "telephoneNumber": "04422334455",
  "systemId":        "SYS-001",
  "guid":            "a1b2c3d4-...",
  "ouname":          "OU=Users,DC=corp,DC=com",
  "server":          "ldap.corp.com",
  "baseDn":          "DC=corp,DC=com",

  "activeUser":      true,
  "isMinDetails":    false,

  "locations": [
    { "id": 5, "name": "Head Office" }
  ],
  "departments": [
    { "id": 3, "name": "IT Department" }
  ],
  "manager": {
    "userId":   88,
    "userName": "jane.smith"
  }
}

Request Fields

Field	Type	Default	Description
`pageNumber`	Integer	1	Page number (1-based)
`pageSize`	Integer	30	Results per page
`userId`	Integer	—	Exact match on internal user ID
`userName`	String	—	Exact match on login username
`fullName`	String	—	Exact match on display name
`emailAddress`	String	—	Exact match on email address
`employeeId`	String	—	Exact match on HR employee ID
`cellNo`	String	—	Exact match on mobile number. When `countryCode` is also provided, matches both `cellNo` and `countryCode + cellNo` (OR).
`countryCode`	String	—	Country dialing prefix (e.g. `"+91"`). Used together with `cellNo` to also match the prefixed form.
`telephoneNumber`	String	—	Exact match on telephone number
`systemId`	String	—	Exact match on system/integration ID
`guid`	String	—	Exact match on AD GUID
`ouname`	String	—	Exact match on AD Organizational Unit name
`server`	String	—	Exact match on LDAP server
`baseDn`	String	—	Exact match on LDAP base DN
`activeUser`	Boolean	false	When `true`, restricts results to active users (`userStatus = 0`)
`isMinDetails`	Boolean	true	When `true`, returns minimal user fields. Set to `false` for full profile.
`locations`	Array of `{id, name}`	—	Filter by location — resolve by `id` (Integer) or `name` (String). Multiple locations use IN.
`departments`	Array of `{id, name}`	—	Filter by department — resolve by `id` (Integer) or `name` (String). Multiple departments use IN.
`manager`	Object `{userId, userName}`	—	Filter users reporting to this manager. Resolved by `userId` (Integer) first, then `userName` (String).

⚠️ userAdditionalFields not supported. This endpoint searches only standard user profile fields. Custom/additional user fields cannot be used as search filters.

Response

● 200 OK

JSON

{
  "search": {
    "pageNumber": 1,
    "pageSize":   30,
    "userName":   "john.doe"
  },
  "users": [
    {
      "userId":       105,
      "userName":     "john.doe",
      "fullName":     "John Doe",
      "emailAddress": "john.doe@company.com",
      "cellNo":       "9876543210",
      "employeeId":   "EMP-1001",
      "department":   { "id": 3, "name": "IT Department" },
      "location":     { "id": 5, "name": "Head Office" }
    }
  ],
  "excutionTime": 45
}

When isMinDetails: true (default), each user object contains only key identifying fields. Set isMinDetails: false to receive the full user profile including all attributes. The response field is spelled excutionTime (not executionTime) — this matches the server's serialized output.

Account & Security

POST /user/unlockAccount Unlock a locked user account ▼

Called after too many failed login attempts. The client IP is captured server-side from the HTTP request.

Request Body (UserSecurity)

{
  "userName": "john.doe",
  "password": "NewP@ss123"
}

UserSecurity Fields

Field	Type	Description
`userName`	String	Login username to unlock
`password`	String	New password to set on unlock
`question`	String	Security question (used for verification)
`questionAnswer`	String	Answer to the security question
`secretPin`	Integer	Secret PIN for additional verification

Response

204 No Content

POST /user/forgotPassword Trigger a password reset for a user ▼

Initiates the password reset flow. Depending on the configured channel, an email or SMS with a reset link/OTP will be sent to the user. The client IP is captured from the HTTP request.

Request Body (UserSecurity)

{
  "userName": "john.doe"
}

Response

204 No Content

POST /user/updatePrivacyDetails Set or update a user's security question and answer ▼

Request Body (UserSecurity)

{
  "userName": "john.doe",
  "question": "What is your mother's maiden name?",
  "questionAnswer": "Smith",
  "secretPin": 4821
}

Response

204 No Content

POST /user/resetADPassword Create and reset an Active Directory user's password ▼

Used for AD-integrated environments. Generates a new password for the specified AD user and resets it in the directory.

Query Parameters

Parameter	Type	Required	Description
`username`	String	REQUIRED	AD login username to reset

Example Request

POST /user/resetADPassword?username=john.doe
X-API-KEY: your-api-key
TOKEN: your-token

Response Body

{
  "status": "SUCCESS",
  "userName": "john.doe",
  "temporaryPassword": "Tmp#8xKq2!",
  "message": "Password reset successfully in Active Directory"
}

All Asset API endpoints use the same authentication headers as Ticket APIs.

Header	Type	Required	Description
`int-log-id`	String	REQUIRED	Integration log identifier for tracing
`X-API-KEY`	String	REQUIRED	API key credential
`TOKEN`	String	REQUIRED	Authentication token
`Content-Type`	String	REQUIRED	`application/json` for JSON endpoints; `multipart/form-data` for file uploads

Asset Lifecycle

POST /asset/create Create a new asset (CI) in CMDB ▼

Request Body

{
  "requestType": "CREATE_ASSET",
  "requestTime": "2024-06-01T10:00:00.000Z",
  "integrationLogId": "LOG-001",
  "asset": {
    "itemType": {
      "itemTypeId": 1,
      "itemType": "Laptop"
    },
    "siteId": 1,
    "systemName": "LAPTOP-WS-001",
    "assetNumber": "AST-2024-001",
    "allocatedUser": {
      "userId": 42,
      "userName": "john.doe",
      "firstName": "John",
      "lastName": "Doe"
    },
    "location": {
      "id": 5,
      "name": "Head Office"
    },
    "department": {
      "id": 3,
      "name": "IT Department"
    },
    "extensionNumber": "1234",
    "mappingKeyValueOne": "SN123456",
    "mappingKeyValueTwo": "MAC:AA:BB:CC:DD:EE",
    "additionalParams": {
      "attribute1": { "itemDetailsId": 101, "data": "Intel Core i7" },
      "attribute2": { "itemDetailsId": 102, "data": "2024-01-15" },
      "attribute3": { "itemDetailsId": 103, "data": "2024-01-15 14:30" },
      "attribute4": { "itemDetailsId": 104, "data": "Option1,Option2" },
      "attribute5": { "itemDetailsId": 105, "data": "SelectedOption" },
      "attribute6": {
        "itemDetailsId": 106,
        "assetGrid": {
          "noOfRow": 2,
          "rows": [
            {
              "attribute1": { "itemDetailsId": 201, "data": "row1-col1-value" },
              "attribute2": { "itemDetailsId": 202, "data": "row1-col2-value" }
            },
            {
              "attribute1": { "itemDetailsId": 201, "data": "row2-col1-value" },
              "attribute2": { "itemDetailsId": 202, "data": "row2-col2-value" }
            }
          ]
        }
      }
    },
    "assetHardwareOsComponents": {
      "operatingSystem": "Windows 11 Pro",
      "osVersion": "23H2",
      "processor": "Intel Core i7-12700",
      "ram": "16384"
    },
    "assetmakeManufacturer": {
      "make": "Dell",
      "model": "Latitude 5540",
      "serialNumber": "SN123456",
      "warrantyExpiryDate": "2027-06-01"
    },
    "assetpurchase": {
      "purchaseDate": "2024-01-15",
      "purchasePrice": "85000",
      "vendor": "Dell Technologies"
    }
  }
}

Response Body

{
  "requestType": "CREATE_ASSET",
  "requestTime": "2024-06-01T10:00:00.000Z",
  "responceTime": "2024-06-01T10:00:01.000Z",
  "integrationLogId": "LOG-001",
  "assetId": 1023,
  "assetNumber": "AST-2024-001",
  "asset": { ... }
}

AssetDTO — Key Fields

Field	Type	Description
`itemType`	Object	Asset item type — `itemTypeId` (Integer) + `itemType` (String)
`siteId`	Integer	Site identifier (default: 1)
`systemName`	String	Hostname / system name of the asset
`assetNumber`	String	Unique asset tag / number
`allocatedUser`	Object	User the asset is assigned to
`location`	Object	Physical location — `id` + `name`
`department`	Object	Department — `id` + `name`
`extensionNumber`	String	Extension / phone number
`mappingKeyValueOne`	String	Custom mapping key 1 (e.g. serial number)
`mappingKeyValueTwo`	String	Custom mapping key 2 (e.g. MAC address)
`additionalParams`	Object	Custom additional fields — see field-type reference below. No `updated` flag required for create or update.
`assetHardwareOsComponents`	Object	Hardware/OS details — OS, processor, RAM, etc.
`assetmakeManufacturer`	Object	Make, model, serial number, warranty
`assetpurchase`	Object	Purchase date, price, vendor
`assetamcWarranty`	Object	AMC / warranty contract details
`assetcostDetails`	Object	Cost centre and depreciation details

additionalParams — Field Type Reference

Each entry in additionalParams maps a slot (attribute1 … attribute50+) to an AssetAttribute object. The key field is itemDetailsId (Integer — obtained from the asset item type configuration API). For update, the service resolves the existing record by itemDetailsId or by field name lookup — no updated flag is required. For grid fields use assetGrid instead of data.

Field Type	Type ID	`data` Format	Example
Text Box	1	Plain string. Must match configured regex/mask if set.	`"data": "Intel Core i7"`
Select Box (Dropdown)	2	Exact option value string from the configured list.	`"data": "Hardware"`
Date And Time Field	3	`yyyy-MM-dd HH:mm` (24-hour)	`"data": "2024-01-15 14:30"`
Text Area	4	Multi-line plain text string.	`"data": "Additional notes"`
Radio Button	5	Exact option value string.	`"data": "Yes"`
Multi Select Box	6	Comma-separated option values. No spaces around comma.	`"data": "Option1,Option2"`
Check Box (YES/NO)	7	`"true"` or `"false"` as string.	`"data": "true"`
Title / Sub-Title / Label / HTML Content	8, 9, 10, 17	Display-only. Omit entirely.	—
Searchable Multi Select Box	12	Comma-separated option values.	`"data": "Tag1,Tag2"`
Grid Control / Calendar Event	13, 18	No `data` field. Use `assetGrid` object with `noOfRow` and `rows` array.	See grid example below
File Upload	14	Cannot be submitted inline. Use attachment upload endpoint separately.	—
Date Field	15	`yyyy-MM-dd`	`"data": "2024-01-15"`
Hyperlink	20	Valid URL string.	`"data": "https://example.com"`
Time Field	21	`HH:mm` (24-hour)	`"data": "09:30"`
Editable Select Box	22	Existing option or free-text string.	`"data": "Custom Value"`
Editable Multi Select Box	23	Comma-separated values (existing options or free-text).	`"data": "Value1,Value2"`

Grid Control — Asset Attribute Structure

JSON

"additionalParams": {
  "attribute6": {
    "itemDetailsId": 106,
    "assetGrid": {
      "noOfRow": 2,
      "rows": [
        {
          "attribute1": { "itemDetailsId": 201, "data": "Row 1 — Column A value" },
          "attribute2": { "itemDetailsId": 202, "data": "Row 1 — Column B value" },
          "attribute3": { "itemDetailsId": 203, "data": "2024-01-15" }
        },
        {
          "attribute1": { "itemDetailsId": 201, "data": "Row 2 — Column A value" },
          "attribute2": { "itemDetailsId": 202, "data": "Row 2 — Column B value" },
          "attribute3": { "itemDetailsId": 203, "data": "2024-01-20" }
        }
      ]
    }
  }
}

Asset grid notes: Use assetGrid (not grid) for asset fields. noOfRow must equal the number of entries in the rows array. Column itemDetailsId values are the child column IDs from the asset item type configuration, not the parent grid field ID. Column data formats follow the same field-type rules above.

POST /asset/update Update an existing asset by assetId or assetNumber ▼

The request body follows the same structure as Create Asset. Provide assetId or assetNumber inside the asset object to identify the record. Only include the fields you want to change — the server merges them onto the existing record. No updated flag is required anywhere — additional params are resolved and updated directly by itemDetailsId or field name lookup.

Request Body

JSON

{
  "requestType":     "UPDATE_ASSET",
  "requestTime":     "2024-06-01T11:00:00.000Z",
  "integrationLogId": "LOG-002",
  "asset": {
    "assetId":     1023,
    "assetNumber": "AST-2024-001",
    "systemName":  "LAPTOP-WS-001-RENAMED",
    "siteId":      1,

    "allocatedUser": {
      "userId":    55,
      "userName":  "jane.smith",
      "firstName": "Jane",
      "lastName":  "Smith"
    },
    "location":   { "id": 5, "name": "Head Office" },
    "department": { "id": 3, "name": "IT Department" },

    "extensionNumber":    "1234",
    "mappingKeyValueOne": "SN-UPDATED",
    "mappingKeyValueTwo": "MAC:11:22:33:44:55",

    "additionalParams": {
      "attribute1": { "itemDetailsId": 101, "data": "Intel Core i9" },
      "attribute2": { "itemDetailsId": 102, "data": "2024-06-01" },
      "attribute3": { "itemDetailsId": 103, "data": "2024-06-01 10:30" },
      "attribute4": { "itemDetailsId": 104, "data": "Option1,Option2" },
      "attribute5": { "itemDetailsId": 105, "data": "SelectedOption" },
      "attribute6": {
        "itemDetailsId": 106,
        "assetGrid": {
          "noOfRow": 1,
          "rows": [
            {
              "attribute1": { "itemDetailsId": 201, "data": "row1-col1-value" },
              "attribute2": { "itemDetailsId": 202, "data": "row1-col2-value" }
            }
          ]
        }
      }
    },

    "assetHardwareOsComponents": {
      "operatingSystem": "Windows 11 Pro",
      "osVersion":       "23H2",
      "processor":       "Intel Core i9-13900",
      "ram":             "32768"
    },
    "assetmakeManufacturer": {
      "make":               "Dell",
      "model":              "Latitude 5540",
      "serialNumber":       "SN-UPDATED",
      "warrantyExpiryDate": "2027-06-01"
    },
    "assetpurchase": {
      "purchaseDate":  "2024-01-15",
      "purchasePrice": "95000",
      "vendor":        "Dell Technologies"
    }
  }
}

AssetDTO — Key Fields

Field	Type	Required	Description
`assetId`	Integer	YES*	Internal asset ID — preferred identifier. Takes priority over `assetNumber`.
`assetNumber`	String	YES*	Asset tag / number. Used to identify the asset when `assetId` is not provided.
`systemName`	String	optional	Hostname / system name of the asset
`siteId`	Integer	optional	Site identifier (default: 1)
`allocatedUser`	Object	optional	Reassign the asset to a different user. Provide `userId` (Integer) or `userName` (String).
`location`	Object `{id, name}`	optional	Update physical location
`department`	Object `{id, name}`	optional	Update department
`extensionNumber`	String	optional	Extension / phone number
`mappingKeyValueOne`	String	optional	Custom mapping key 1 (e.g. serial number)
`mappingKeyValueTwo`	String	optional	Custom mapping key 2 (e.g. MAC address)
`additionalParams`	Object	optional	Custom additional fields. No `updated` flag needed — see field-type reference in Create Asset. Records are resolved by `itemDetailsId` or field name and updated directly.
`assetHardwareOsComponents`	Object	optional	OS, processor, RAM details
`assetmakeManufacturer`	Object	optional	Make, model, serial number, warranty
`assetpurchase`	Object	optional	Purchase date, price, vendor
`assetamcWarranty`	Object	optional	AMC / warranty contract details
`assetcostDetails`	Object	optional	Cost centre and depreciation details

Response

● 200 OK

JSON

{
  "requestType":     "UPDATE_ASSET",
  "responceTime":    "2024-06-01T11:00:01.000Z",
  "integrationLogId": "LOG-002",
  "assetId":         1023,
  "assetNumber":     "AST-2024-001",
  "asset": { ... }
}

POST /asset/updateStatus Change the lifecycle status of an asset ▼

Transitions an asset to a new lifecycle state (e.g. In Use → Under Maintenance → Retired). The target state is identified via the asset.filter object using either its id (flow details ID) or value (status name string). The server records the transition in asset history automatically.

Request Body

JSON

{
  "requestType":      "UPDATE_STATUS",
  "requestTime":      "2024-06-01T12:00:00.000Z",
  "integrationLogId": "LOG-003",
  "asset": {
    "assetId":     1023,
    "assetNumber": "AST-2024-001",
    "filter": {
      "id":    3,
      "value": "Retired"
    }
  }
}

Key Fields

Field	Type	Required	Description
`asset.assetId`	Integer	YES*	Internal asset ID — preferred identifier
`asset.assetNumber`	String	YES*	Asset tag — used to identify the asset when `assetId` is not provided
`asset.filter.id`	Integer	YES*	Flow details ID of the target lifecycle state. Takes priority over `filter.value`.
`asset.filter.value`	String	YES*	Target lifecycle status name (e.g. `"Retired"`, `"Under Maintenance"`). Used when `filter.id` is not provided. Must match the configured status name exactly.

Provide either filter.id or filter.value to identify the target state. Use the Asset Flow / Status configuration API to retrieve valid IDs and names for the asset's item type.

Response

● 200 OK

JSON

{
  "requestType":  "UPDATE_STATUS",
  "responceTime": "2024-06-01T12:00:01.000Z",
  "assetId":      1023,
  "assetNumber":  "AST-2024-001"
}

Asset Retrieve

GET /asset/get/{id}/id Get full asset details by numeric asset ID ▼

Path Parameters

Parameter	Type	Required	Description
`id`	Integer	REQUIRED	Numeric asset ID returned at creation

Headers

Header	Required
`int-log-id`	REQUIRED
`X-API-KEY`	REQUIRED
`TOKEN`	REQUIRED

Example Request

GET /asset/get/1023/id
int-log-id: LOG-004
X-API-KEY: your-api-key
TOKEN: your-token

Response Body

{
  "assetId": 1023,
  "assetNumber": "AST-2024-001",
  "asset": {
    "assetId": 1023,
    "assetNumber": "AST-2024-001",
    "systemName": "LAPTOP-WS-001",
    "itemType": { "itemTypeId": 1, "itemType": "Laptop" },
    "allocatedUser": { ... },
    "location": { "id": 5, "name": "Head Office" },
    "department": { "id": 3, "name": "IT Department" },
    "additionalParams": { ... },
    "assetHardwareOsComponents": { ... },
    "assetmakeManufacturer": { ... }
  }
}

GET /asset/get/{itemTypeId}/itemTypeId Get assets by item type, filtered by asset number ▼

Path Parameters

Parameter	Type	Required	Description
`itemTypeId`	Integer	REQUIRED	Asset item type ID

Query Parameters

Parameter	Type	Required	Default	Description
`assetNumber`	String	REQUIRED	—	Asset number to filter by
`siteId`	Integer	OPTIONAL	1	Site identifier
`loadChild`	Boolean	OPTIONAL	false	Whether to load child assets

Example Request

GET /asset/get/1/itemTypeId?assetNumber=AST-2024-001&siteId=1&loadChild=false
X-API-KEY: your-api-key
TOKEN: your-token

GET /asset/get/{assetNumber}/assetNumber Get asset by asset number (path variable) ▼

Path Parameters

Parameter	Type	Required	Description
`assetNumber`	String	REQUIRED	Asset number / tag

Query Parameters

Parameter	Type	Required	Default	Description
`siteId`	Integer	OPTIONAL	1	Site identifier
`loadChild`	Boolean	OPTIONAL	false	Load child assets

Example Request

GET /asset/get/AST-2024-001/assetNumber?siteId=1&loadChild=false
X-API-KEY: your-api-key
TOKEN: your-token

GET /asset/get/assetNumber Get asset by asset number (query parameter) ▼

Alternative to the path-variable variant above. Use this form when the asset number contains characters that may conflict with URL path parsing.

Query Parameters

Parameter	Type	Required	Default	Description
`assetNumber`	String	REQUIRED	—	Asset number / tag
`siteId`	Integer	OPTIONAL	1	Site identifier
`loadChild`	Boolean	OPTIONAL	false	Load child assets

Example Request

GET /asset/get/assetNumber?assetNumber=AST-2024-001&siteId=1&loadChild=false
X-API-KEY: your-api-key
TOKEN: your-token

POST /asset/find Search / filter assets with pagination ▼

Request Body

All fields are optional filters combined with AND. String filters use exact match unless noted otherwise. When additionalParams is provided, itemType is also required — the search switches to a dedicated additional-field JOIN query. Grid fields are not supported in the additional params search path — only simple data string fields.

JSON

{
  "pageNumber": 1,
  "pageSize":   30,
  "siteId":     1,

  "itemType": {
    "itemTypeId":      1,
    "itemType":        "Laptop",
    "assetModuleId":   2,
    "assetModuleName": "Hardware"
  },

  "assetNo":    "AST-2024",
  "systemName": "LAPTOP-WS",
  "systemId":   101,
  "assetStatus": "In Use",

  "allocatedUser": {
    "userId":   42,
    "userName": "john.doe",
    "emailId":  "john.doe@company.com"
  },

  "location": [
    { "id": 5, "name": "Head Office" }
  ],
  "department": [
    { "id": 3, "name": "IT Department" }
  ],

  "details":          false,
  "orderBy":          "assetNumber",
  "orderByDirection": "ASC",
  "groupBy":          "",

  "additionalParams": {
    "attribute1": { "itemDetailsId": 101, "data": "Intel Core i7" },
    "attribute2": { "itemDetailsId": 102, "data": "2024-01-15" }
  }
}

Request Fields

Field	Type	Default	Description
`pageNumber`	Integer	1	Page number (1-based); defaults to 1 if 0 is passed
`pageSize`	Integer	30	Results per page; defaults to 30 if 0 is passed
`siteId`	Integer	1	Site scope for the search (defaults to 1 in additional-params path)
`itemType.itemTypeId`	Integer	—	Filter by exact item type ID. Takes priority over `itemType` name.
`itemType.itemType`	String	—	Item type name — used to resolve ID when `itemTypeId` is not provided
`itemType.assetModuleId`	Integer	—	Filter all item types within a module when `itemTypeId` is 0
`itemType.assetModuleName`	String	—	Module name — used to resolve `assetModuleId` when not provided
`assetNo`	String	—	LIKE `%value%` match on asset number
`systemName`	String	—	Exact match on system/host name
`systemId`	Integer	—	Exact match on system ID
`assetStatus`	String	—	Lifecycle status name (e.g. `"In Use"`, `"Retired"`). Resolved to `filterId` internally — must match configured status name exactly. Requires `itemType`.
`allocatedUser.userId`	Integer	—	Filter by allocated user ID. Takes priority over `userName`.
`allocatedUser.userName`	String	—	Filter by allocated user login name
`allocatedUser.emailId`	String	—	Filter by allocated user email — used as fallback if `userId` and `userName` don't resolve
`location`	Array of `{id, name}`	—	Filter by location — resolved by `id` or `name`. Multiple values use IN.
`department`	Array of `{id, name}`	—	Filter by department — resolved by `id` or `name`. Multiple values use IN.
`details`	Boolean	false	`false` = summary list (AssetMinDTO). `true` = full asset objects including all components and additional params.
`orderBy`	String	—	Column(s) to sort by (comma-separated). In additional-params path, prefixed with `am.` automatically.
`orderByDirection`	String	DESC	`ASC` or `DESC`
`groupBy`	String	—	Column to group by (passed through to query)
`additionalParams`	Object	—	Custom field filters — see Additional Params Search section below. Requires `itemType` when used.

Additional Params Search

⚠️ When additionalParams is present, the search switches to a dedicated JOIN query path that LEFT JOINs the assetdetails table for each populated attribute and applies an exact match on AssetValue. itemType is required in this mode. Grid fields (assetGrid) are not supported — only simple data string values work as search filters.

JSON — additionalParams search example

{
  "pageNumber": 1,
  "pageSize":   30,
  "siteId":     1,
  "itemType": { "itemTypeId": 1 },
  "additionalParams": {
    "attribute1": { "itemDetailsId": 101, "data": "Intel Core i7" },
    "attribute3": { "itemDetailsId": 103, "data": "2024-01-15" }
  }
}

Field	Type	Description
`attribute1` … `attribute50`	Object	Named slot. Omit slots you don't want to filter on.
`attribute{n}.itemDetailsId`	Integer	The field's `itemDetailsId` from the asset item type configuration — used to JOIN the correct column
`attribute{n}.data`	String	Value to match — exact match against `AssetValue` column. Use the same format as when creating the asset (e.g. `yyyy-MM-dd` for date fields, comma-separated for multi-select).

The slot names (attribute1, attribute2, …) must match the field name registered in the asset item type configuration. Contact your SapphireIMS admin to get the correct itemDetailsId and slot mapping. Grid fields store data in a separate structure and cannot be filtered via this path.

Response

● 200 OK

JSON — summary (details: false)

{
  "search": { "pageNumber": 1, "pageSize": 30 },
  "assets": [
    {
      "assetId":     1023,
      "assetNumber": "AST-2024-001",
      "systemName":  "LAPTOP-WS-001",
      "itemType":    { "itemTypeId": 1, "itemType": "Laptop" },
      "assetStatus": "In Use",
      "allocatedUser": { "userId": 42, "userName": "john.doe" },
      "location":    { "id": 5, "name": "Head Office" },
      "department":  { "id": 3, "name": "IT Department" }
    }
  ],
  "excutionTime": 38
}

Set details: true to receive full AssetDTO objects (including all components and additional params) in assetDetails instead of the summary assets array. The response field is spelled excutionTime — this matches the server's serialized output.

Asset Upload & System

POST /asset/assetupload Upload a file attachment to an asset ▼

Multipart/form-data upload. Set Content-Type: multipart/form-data.

Form Fields (AssetUploadModel)

Field	Type	Required	Description
`assetId`	Integer	OPTIONAL*	Numeric asset ID (provide assetId or assetNumber)
`assetNumber`	String	OPTIONAL*	Asset tag / number (provide assetId or assetNumber)
`comment`	String	OPTIONAL	Comment / description for the attachment
`file`	File	REQUIRED	The file to upload

Example (curl)

curl -X POST https://{{your-domain}}/asset/assetupload \
  -H "X-API-KEY: your-api-key" \
  -H "TOKEN: your-token" \
  -H "int-log-id: LOG-005" \
  -F "assetId=1023" \
  -F "comment=Purchase invoice" \
  -F "file=@invoice.pdf"

POST /asset/systemId Get asset field metadata for a given system ▼

Returns the field configuration (field IDs, display names, field types) for a system's asset item type. Use the returned itemDetailsId values when populating additionalParams in create/update calls.

Query Parameters

Parameter	Type	Required	Default	Description
`siteId`	Integer	OPTIONAL	1	Site identifier

Request Body (SystemRequestDTO)

{
  "systemId": 7
}

Response Body (AssetFieldMetadataResponseDTO)

{
  "systemId": 7,
  "itemTypeId": 1,
  "itemType": "Laptop",
  "fields": [
    {
      "itemDetailsId": 101,
      "parameterName": "Processor",
      "fieldType": "TEXT",
      "isMandatory": false
    },
    {
      "itemDetailsId": 102,
      "parameterName": "RAM",
      "fieldType": "TEXT",
      "isMandatory": false
    }
  ]
}

POST /asset/updateAssetAcceptance Submit asset acceptance / verification result ▼

Used by endpoint agents (e.g. RPA or asset scanner) to submit the result of a user acceptance check or audit scan. Returns "SUCCESS" on success.

Query Parameters

Parameter	Type	Required	Default	Description
`siteId`	Integer	OPTIONAL	1	Site identifier

Request Body (AssetVerificationSubmissionDTO)

{
  "systemId": "SYS-007",
  "verification_completed": true,
  "user": "john.doe",
  "computer": "LAPTOP-WS-001",
  "reason": "Scheduled quarterly audit",
  "totalAssets": 3,
  "compliance_status": "COMPLIANT",
  "system_unlock": false,
  "assets": [
    { "assetNumber": "AST-2024-001", "status": "FOUND" },
    { "assetNumber": "AST-2024-002", "status": "FOUND" },
    { "assetNumber": "AST-2024-003", "status": "MISSING" }
  ]
}

Request Body Fields

Field	Type	Description
`systemId`	String	System identifier
`verification_completed`	Boolean	Whether the verification process completed
`user`	String	User who performed the verification
`computer`	String	Computer / host name
`reason`	String	Reason or notes for the verification
`totalAssets`	Integer	Total number of assets verified
`compliance_status`	String	Overall compliance result (e.g. "COMPLIANT", "NON_COMPLIANT")
`system_unlock`	Boolean	Whether the system should be unlocked after verification
`assets`	Array<Map>	List of asset records — each map has arbitrary key/value pairs (e.g. assetNumber, status)

Response

"SUCCESS"

SapphireIMS API Reference